<!DOCTYPE html>
<html>
	<head>
		<!-- Update title -->
		<title>Cinder on Windows</title>

		<!-- keywords used for searching -->
		<meta name="keywords" content="guide, windows, msw">
		<meta name="viewport" content="width=device-width, initial-scale=1">

		<!-- reference to Cinder classes -->
   		<!-- <ci seealso dox="[CLASS NAME GOES HERE]" label="[NAME OF LINK]"></ci> -->

   		<!-- master stylesheet - these links will be replaced when compiled -->
		<link rel="stylesheet" href="../../_assets/css/foundation.css">
		<link rel="stylesheet" href="../../_assets/css/prism.css">
		<link rel="stylesheet" href="../../_assets/css/style.css">
		<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,300,600,700' rel='stylesheet' type='text/css'>

		<!-- Place additional stylsheet links here, which will be copied over when compiled (optional) -->
		
	</head>

	<body id="guide-contents" class="language-c++">

		<!-- CONTENT STARTS HERE -->

		<h1>Windows Notes</h1>
		<p>These are some general notes on Cinder's implementation on the Microsoft Windows platform.</p>
		
		<section>
			<h2>Targeting</h2>
			<p>By default Cinder targets Windows 7 and later. This is dictated by the <code>_WIN32_WINNT</code> macro, which is typically defined in your project's <strong>Preprocessor Definitions</strong> build setting. The value <code>0x0601</code> maps to Windows 7. To target a different version of Windows, you'll need to modify this variable in both your application and Cinder itself, and rebuild Cinder.</p>

			<center><img class="shadow" width="626" height="449" src="msw_notes/vc_target.png" /></center>
		</section>

		<section>
			<h2>Development Requirements</h2>
			<p>Cinder supports Visual Studio 2019, including the free <em>Community</em> edition, and requires the v142 toolset. Additionally, Cinder requires the c++17 language standard (<code>std:c++17</code>).</p>
		</section>

		<section>
			<h2>ANGLE</h2>
			<p>In addition to the normal <em>Debug</em> and <em>Release</em> build configurations, Cinder also ships with <em>Debug_ANGLE</em> and <em>Release_ANGLE</em> variants. <a href="https://code.google.com/p/angleproject/">ANGLE</a>, which stands for Almost Native Graphics Library, is an implementation of OpenGL ES in terms of DirectX. This can be useful for supporting machines where OpenGL drivers can't be guaranteed or are of poorer quality than DirectX. TinderBox can setup your project to use ANGLE.</p>
		</section>

		<section>
			<h2>External Preprocessor Definitions (Advanced)</h2>
			<p>In some instances, it can be useful to modify libcinder's preprocessor flags without requiring direct modification of its project. This is particularly useful when using Cinder in a project via a git submodule. Some common cases include the <ci>CI_MIN_LOG_LEVEL</ci>, as described in <a href="../logging/index.html">this guide</a>, and compile time macros that adjust the way that <ci>CI_ASSERT()</ci> works.</p>

			<ul>
			<li>To use this technique you need to add cinder.vcxproj to your main project's solution file. This can be convenient in its own right when working on a large project, as it allows direct navigation of Cinder's codebase from within your application.
			</li>
			<li>cinder.vcxproj is configured to search for a file called <code>CinderMswUserDefines.h</code>, which will be added as a "Forced Include File", i.e. its contents will be prepended to every source file built in libcinder. The first place that cinder.vcxproj searches for this file is in the same directory as your project's solution (.sln) file, which lives outside of the Cinder repository. If you don't provide a <code>CinderMswUserDefines.h</code> file, the empty default at <code>include\cinder\msw</code> will be used. To override this default, create a <code>CinderMswUserDefines.h</code> file in the same directory as your project's .sln file, and add the preprocessor directives to that. You can also add this same setting to any vcxproj file that you want to make use of the same preprocessor adjustments. Here's a screen capture of what that looks like:
				<center><img class="shadow" width="626" height="449" src="msw_notes/forced_includes.png" /></center>
			</li>
			<li>For this file to also be found in your projects, you should add an 'Additional Include Directories' to your project for $(SolutionDir), which looks like:
				<center><img class="shadow" width="626" height="449" src="msw_notes/solution_dir_include.png" /></center>
			</li>
			<li>Lastly, you may want to make cinder.lib a dependency on your app's target, which forces it to be rebuilt whenever necessary you modify your <code>CinderMswUserDefines.h</code> file (or any other source in libcinder). You can do this by going to the Solution Explorer and right clicking on your solution, then going to the 'Common Properties -> Project Dependencies' page.
			</li>
			</ul>
			<p>Now any additions to <code>CinderMswUserDefines.h</code> will customize the cinder.lib that your app links to accordingly.</p>
		</section>

		<!-- END CONTENT -->

		<!-- Scripts -->
		<script src="../../_assets/js/prism.js" type="text/javascript"></script>
		<!-- Place additional scripts here (optional) -->
		<!-- <script type="text/javascript"></script> -->

	</body>
</html> 